//--------------------------------------------------------------------------
// 
//  Copyright (c) Chili Software.  All rights reserved. 
// 
//  File: ICustomDataTypesStorage.cs
//
//  Description: Provides data type flexibility for storages.
// 
//--------------------------------------------------------------------------

using System;

namespace Chili.Opf3.Storages
{
	/// <summary>This interface is implemented by a storage that does not support all simple types of the .NET framework.</summary>
	/// <remarks>
	/// A storage that does not natively support all simple types of the .NET framework has to implement this interface. 
	/// It allows the storage to change the type that comes from the storage to a type that is supported by the .NET framework
	/// and to change it back to a type that is supported by the storage.
	/// </remarks>
	/// <example>
	/// Firebird does, for example, not support the .NET type Boolean. Therefore a field with type integer is used
	/// in the database. By implementing this interface the integer from the database is converted to an boolean 
	/// (during load of the object). When saving the object the boolean of the object is converted back to an integer.
	/// <code lang="C#">
	/// object ICustomDataTypesStorage.ChangeFromDataType(object obj, Type targetType)
	/// {
	///     if (!(obj is bool) &amp;&amp; targetType == typeof(bool))
	///         return Convert.ToBoolean(obj);
	///     return obj;
	/// }
	///
	/// object ICustomDataTypesStorage.ChangeToDataType(object obj)
	/// {
	///     if (obj is bool)
	///         return Convert.ToInt32((bool)obj);
	///     return obj;
	/// }
	/// </code>
	/// </example>
	public interface ICustomDataTypesStorage : IStorage
	{
		/// <summary>
		/// Allows to convert from the type in the storage to the target type of the object.
		/// </summary>
		/// <param name="value">Value loaded from the storage.</param>
		/// <param name="targetType">The type of the member of the persistent object.</param>
		/// <returns>The value converted to the target type.</returns>
		object ChangeFromDataType(object value, Type targetType);

		/// <summary>
		/// Allows to convert from the type of the object to a type that is supported by the storage.
		/// </summary>
		/// <param name="value">Value from the persistent object that is converted to a type supported by the storage.</param>
		/// <returns>The value converted to a type that is supported by the storage.</returns>
		object ChangeToDataType(object value);
	}
}
